File API

API Endpoint

All requests for the File API should be sent to:

https://www.filestackapi.com/api/file

Related: Tutorial On Performing A Workflow API

Security

Security may be required for certain API requests, such as overwrite and delete, or if security has been enabled for the application. For the File API, security credentials should be provided in the form of query parameters or using HTTP basic auth:

Query Parameters

?policy=POLICY&signature=SIGNATURE

Basic Authentication

• User: “app”
• Password: APP_SECRET_KEY

Example for file overwrite:

curl -X POST \
    -u "app:SECRET_KEY" \
    -d "url=SOME_URL" "https://www.filestackapi/api/file/hGdfDXDSSNyVhVa0UeiB"

Please refer to our section on security for more information on generated policies and signatures.

Download

Retrieves file via a Filestack handle. Requires policy and signature only when security has been enabled on account.

Query Params

Store

Uploads a file directly to any of our supported backends. This will return JSON metadata, including a Filestack URL for the file. You must provide your APIKEY as a query parameter and a file as multipart form data. Alternatively, you may provide a public URL as a file through the “url” parameter in body of the request.

Requires policy and signature only when security has been enabled on account.

Please refer to our documentation on storage providers to find out more on configuring custom cloud storage for your account.

Provider

Where to store the file. The default is S3. Other options include ‘azure’,‘dropbox’, ‘rackspace’ and ‘gcs’. You must have the chosen provider configured in the developer portal to enable this feature.

Query Params

Request

curl -X POST \
    -d url="https://assets.filestackapi.com/watermark.png" \
    "https://www.filestackapi.com/api/store/S3?key=MY_API_KEY"

curl -X POST \
    --data-binary @filename.png \
    --header "Content-Type:image/png" \
    "https://www.filestackapi.com/api/store/S3?key=MY_API_KEY"

Response

{
    "url": "https://cdn.filestackcontent.com/s7tdGfE5RRKFUxwsZoYv",
    "size": 8331,
    "type": "image/png",
    "filename": "watermark.png",
    "key": "a1RyBxiglW92bS2SRmqM_watermark.png"
}

Overwrite

Overwrites a handle with a new file supplied as the body of the request. This action requires security.

Query Params

Request

curl -X POST \
    --data-binary @filename.txt \
    --header "Content-Type:text/plain" \
    "https://www.filestackapi.com/api/file/Bc2FQwXReueTsaeXB6rO?policy={POLICY}&signature={SIGNATURE}"

Response

{
    "url": "https://cdn.filestackcontent.com/Bc2FQwXReueTsaeXB6rO",
    "mimetype": "plain/text",
    "isWriteable": true,
    "size": 19,
    "filename": "filename.txt"
}

Delete

Deletes a file via its handle. This request requires security.

Query Params

Request

curl -X DELETE \
"https://www.filestackapi.com/api/file/{HANDLE}?key={APIKEY}&policy={POLICY}&signature={SIGNATURE}"

Metadata

Get a JSON payload of your uploaded file metadata. This metadata is generated on the fly and is not stored in the Filestack database. Requires policy and signature when using exif=true.

Query Params

Query parameters to the metadata endpoint determine which fields will be returned in the JSON response.

If your file is an image and you would like to know its width and height you can use imagesize task from our Processing API.

Hashing

Return a hash of the file.

Storage

Get storage information.

Request

curl -X GET "https://www.filestackapi.com/api/file/DCL5K46FS3OIxb5iuKby/metadata"

Response

{
    "mimetype": "image/png",
    "uploaded": 1431950945811.783,
    "container": "fp-documentation-assets",
    "writeable": true,
    "filename": "dtKZNd1J.png",
    "location": "S3",
    "key": "kWg7nloGTWmHFi5nlbF9_dtKZNd1J.png",
    "path": "kWg7nloGTWmHFi5nlbF9_dtKZNd1J.png",
    "size": 270
}